Post Title

Project

Redesign kevinmcnellis.com as a modern, academic‑style site using Quarto and host it on GitHub Pages. This brief gives an AI coding agent everything it needs to implement the redesign end‑to‑end.

⸻

1. Snapshot Audit of Current Site • Platform: WordPress. • Critical issue: Front page shows a Sass Compiling Error from the wp-scss plugin (cache directory permission denied). This breaks styles and is a signal to migrate rather than patch. • Information architecture (observed nav): Home, About, Services, Blog, Contact. Content tone is policy/analysis consulting; several blog posts exist. • Branding: Name + headshot, simple logo; footer has privacy/accessibility links and social links.

Implications for migration • Export page/post content and assets from WordPress (text, images). • Rebuild site statically in Quarto; replicate essential pages and move blog posts to /posts/ with clean slugs. • Replace WP cookie banner, contact form, and analytics with static‑site‑friendly equivalents.

⸻

2. Target Look & Features (based on the reference gallery)

We want the site to match the aesthetic/structure of Quarto academic examples (e.g., clear typography, left‑to‑right navbar, profile/hero, sections for Publications / Posts / Projects, and tidy listing pages). Key features to implement: • Responsive academic layout with clean navbar, profile card, and modular sections (personal site pattern). • Listings for posts, publications, talks, media, and projects using Quarto’s built‑in listings with cards/grids. • Data‑driven pages (e.g., publications via YAML/CSV) + category filters. • Dark‑mode toggle (theme supports it). • RSS for posts and discoverability metadata. • Easy “includes” for reusable snippets (e.g., social share, badges). • Lightweight social sharing buttons and optional academic badges.

⸻

3. Technical Stack & Hosting • Generator: Quarto (>= 1.5). • Language: .qmd (Quarto Markdown), site config in _quarto.yml. • Themes: Start with cosmo/flatly/sandstone or litera; allow custom SCSS overrides. • Hosting: GitHub Pages via gh-pages branch using either quarto publish gh-pages or a GitHub Action. • Custom domain: kevinmcnellis.com (apex + www)—set DNS and repo settings accordingly.

⸻

4. Repository Layout (proposed)

kevinmcnellis-site/ ├─ _quarto.yml # site config ├─ index.qmd # home with profile & CTA ├─ about.qmd # bio, headshot ├─ services.qmd # consulting offerings ├─ contact.qmd # email, form endpoint ├─ posts/ # blog posts (.qmd) │ ├─ 2025-10-…-post-title.qmd ├─ publications/ # data-driven content │ ├─ publications.yml # items listed via listings ├─ projects/ ├─ media/ # press/testimony etc. ├─ files/ # PDFs, slides, CV ├─ images/ # site images ├─ styles/ │ ├─ styles.scss # optional custom vars ├─ includes/ # reusable partials │ ├─ social-share.html │ ├─ badges.html ├─ .github/workflows/ │ └─ publish.yml # CI render+deploy (optional) └─ README.md

⸻

5. Minimum Viable Pages & Content Model

Home (index.qmd) • Hero/profile (headshot, 2–3 line value prop). • Featured sections: Services, Latest Posts (listing), Selected Publications, Contact CTA.

About • Bio with short + long sections; headshot; download CV.

Services • Three focus areas (Policy design, Synthesizing research, Congressional procedure) with bullets and contact CTA.

Posts • Listing page with cards grid (title, date, summary, tags). • Individual post template (posts/YYYY-MM-dd-title.qmd) with author bio footer.

Publications • Data‑driven listing from publications.yml with fields: title, authors, venue, year, doi|url, type, categories, image.

Projects / Media / Testimony (optional now) • Simple listing‑first pages; can be staged later.

Contact • Email link + form endpoint (Formspree or Basin). Include anti‑spam honeypot.

⸻

6. _quarto.yml (starter)

project: type: website output-dir: _site

website: title: “Kevin McNellis” site-url: “https://www.kevinmcnellis.com” description: “Policy analysis, budget process, and economic modeling.” navbar: right: - href: index.qmd text: Home - about.qmd - services.qmd - text: Writing href: posts/index.qmd - text: Publications href: publications/index.qmd - contact.qmd page-footer: left: “© {year} Kevin McNellis” right: “Made with Quarto” cookie-consent: false # add later if needed

format: html: theme: litera css: styles/styles.scss toc: true smooth-scroll: true code-copy: true link-external-newwindow: true

listing: # global defaults; pages can override contents: posts type: grid sort: “-date”

⸻

7. Listings & Data‑Driven Content • Use Quarto Listings for posts/publications with card/grid view and filters. • Store publications in publications.yml; render with a page that declares listing: options and contents: pointing to the YAML. • For category‑specific pages, use include:/exclude: filters and categories fields.

⸻

8. Styling & Components • Start from a Quarto Bootstrap theme; adjust variables in styles.scss (brand color, font scale, link styles). • Create includes/social-share.html and includes/badges.html; inject via page‑level include-after-body or _quarto.yml format.html.include-after-body. • Dark mode: use theme that supports it; optionally add theme toggle.

⸻

9. Analytics, SEO, and Feeds • Set site-url for canonical links & RSS. • Add GA4 ID via _quarto.yml (google-analytics:) or include header snippet. • Generate RSS feeds for posts; ensure links are present. • Add basic Open Graph/Twitter Card metadata (title, description, image) via page YAML or defaults.

⸻

10. Contact Form Options (no server) • Formspree or Getform/Basin: simple endpoint POST from static site. • Add honeypot + required fields. • Provide mailto: fallback for users blocking scripts.

⸻

11. Deployment to GitHub Pages

Two supported setups (choose one):

A. Local publish (simplest) • Developer runs quarto publish gh-pages, which builds the site and pushes to gh-pages branch. • Repo → Settings → Pages → Source: gh-pages.

B. GitHub Actions (auto‑build on push) • Workflow renders Quarto on each commit to main and deploys to gh-pages. • Keep source on main, built site on gh-pages.

Custom domain • Add CNAME file at publish root with www.kevinmcnellis.com (or apex). • Configure DNS: point www CNAME → username.github.io; apex via ALIAS/ANAME or A records to GitHub Pages IPs. • Enable HTTPS in Pages settings.

⸻

12. Migration Plan from WordPress

    1. Export Content

    • Copy page text into .qmd files. • Export blog posts (title, date, slug, summary, body, images). • Download media library assets used in posts/pages.

    2. Recreate IA

    • Map WP pages → Quarto equivalents. • Place posts into posts/YYYY-MM-dd-slug.qmd (retain original dates).

    3. Redirects (preserve SEO & links)

    • If keeping old URLs live briefly: publish small HTML stubs with <meta http-equiv=“refresh” …> to new locations in GitHub Pages branch, or maintain a redirects map via hand‑rolled stubs for top posts. • Update social/profile links to point to new paths.

    4. Decommission WP

    • After verifying DNS cutover and links, cancel old hosting/theme plugins.

⸻

13. Accessibility & Performance Checklist • Color contrast ≥ WCAG AA; focus styles visible. • Semantic landmarks (
    ,

    ,

    ,

    ). • Alt text for images; decorative images with empty alt. • Keyboard nav check on all pages. • Lazy‑load large images, compress hero images, prefer SVG for logos.

⸻

14. Acceptance Criteria (MVP) • Site builds locally and via CI without errors. • Home/About/Services/Contact pages complete; at least 5 posts migrated; publications listing live with ≥10 items. • RSS enabled for posts; GA4 connected; sitemap present; canonical links set. • Custom domain + HTTPS active; 404 page styled; basic social preview image works.

⸻

15. Open Questions for the Owner • Final color palette & type preferences? (system serif/sans or custom Google Fonts) • Do we want a CV page (auto‑built from YAML) and a Talks/Media section now or later? • Which contact form provider to use (Formspree / Basin / Getform)? • Which posts to migrate first (top 10 by importance)?

⸻

16. Suggested Implementation Steps for the Agent
    1. Scaffold repo with the layout above; commit a working _quarto.yml and starter pages.
    2. Add a listing page for posts and publications; wire up YAML‑based publications.
    3. Implement styles.scss with minimal brand tweaks; paginate posts listing (if needed).
    4. Add GA4 and Open Graph defaults; create /files/CV.pdf placeholder.
    5. Configure GitHub Pages + custom domain and HTTPS; verify with a smoke test.
    6. Migrate 5–10 representative posts; create meta‑refresh redirect stubs for top legacy URLs.
    7. Draft docs in README.md to explain how to add posts/publications.

⸻

17. Example Snippets

GitHub Action (CI publish)

name: Publish Quarto site on: push: branches: [ main ] permissions: contents: write jobs: build-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: quarto-dev/quarto-actions/setup@v2 - run: quarto render - uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: _site cname: kevinmcnellis.com

Post front‑matter template

Publication item (YAML)

• title: “Modified-Open Special Rules Return in the House” authors: [“Kevin McNellis”] venue: “Blog” year: 2024 url: “https://kevinmcnellis.com/…” categories: [congress, rules]

⸻

18. Risk & Mitigation • DNS cutover delays → Do changes during low‑traffic window; pre‑validate with username.github.io URL. • Image bloat → Compress with imagemin/Squoosh; serve responsive sizes. • Broken links → Run link checker in CI; keep a redirects map for top legacy slugs.

⸻

19. Deliverables • GitHub repo with Quarto source + CI workflow. • Deployed site on kevinmcnellis.com with custom domain + HTTPS. • Owner’s guide in README.md explaining how to add/edit content. • Optional: color/typography style guide and favicon set.